Hooks
课程导读
这节课介绍 Claude Code 的 Hooks 功能。Hooks 可以在固定节点自动执行预设动作，适合用来做通知、检查、提醒等自动化流程。
一、查看 Hooks 触发时机
Claude Code 官方文档中有 Hooks 的触发时机说明和生命周期图。
Claude Code Hooks 官方文档
| 英文名 | 中文名 | 作用 |
|---|---|---|
SessionStart | 会话开始 | 会话开始、恢复、清空或压缩后重建时触发，可注入项目上下文。 |
Setup | 初始化设置 | 用 --init-only，或打印模式 --init / --maintenance 时触发，适合一次性准备。 |
UserPromptSubmit | 用户提交提示 | 用户 prompt 进入 Claude 前触发，可校验、阻止或补充上下文。 |
UserPromptExpansion | 提示展开 | 用户输入命令展开成 prompt 前触发，可阻止展开或追加上下文。 |
PreToolUse | 工具调用前 | 工具参数生成后、执行前触发，可允许、拒绝、询问、延迟或改写输入。 |
PermissionRequest | 权限请求 | 权限对话框显示前触发，可代替用户批准、拒绝或更新权限规则。 |
PermissionDenied | 权限被拒 | 自动模式分类器拒绝工具调用后触发，可记录并提示模型可重试。 |
PostToolUse | 工具成功后 | 工具成功执行后触发，可给 Claude 反馈、追加上下文或替换输出。 |
PostToolUseFailure | 工具失败后 | 工具失败或报错后触发，用于记录失败并给 Claude 补充纠正信息。 |
PostToolBatch | 工具批次后 | 一批并行工具全部结束后、下一次模型调用前触发，适合批量注入上下文。 |
Notification | 通知 | Claude Code 发送权限、空闲、认证或 elicitation 通知时触发，适合转发提醒。 |
SubagentStart | 子代理开始 | 通过 Agent 工具创建 subagent 时触发，可给子代理注入初始上下文。 |
SubagentStop | 子代理结束 | subagent 完成响应时触发，可阻止其停止并要求继续。 |
TaskCreated | 任务创建 | TaskCreate 创建任务时触发，可强制命名规范或阻止不合格任务。 |
TaskCompleted | 任务完成 | 任务被标记完成时触发，可先跑测试或检查，不通过就阻止关闭。 |
Stop | 主代理停止 | 主 Claude 代理完成回复时触发，可阻止停止并要求继续完成条件。 |
StopFailure | 停止失败 | 轮次因 API 错误结束时触发，用于日志、告警或恢复动作。 |
TeammateIdle | 队友空闲 | Agent team 队友即将空闲时触发，可作为质量门并要求继续工作。 |
InstructionsLoaded | 指令加载 | CLAUDE.md 或 rules 文件加载进上下文时触发，用于审计和可观测性。 |
ConfigChange | 配置变更 | settings、托管策略或 skill 配置变化时触发，可审计或阻止未授权变更。 |
CwdChanged | 目录变化 | 会话中的工作目录改变时触发，可切换环境、工具链或动态监听文件。 |
FileChanged | 文件变化 | 被监听文件在磁盘变更时触发，常用于重新加载 env 或维护 watcher。 |
WorktreeCreate | 创建工作树 | --worktree 或 worktree 隔离 subagent 创建工作副本时触发，可替换默认 git 行为。 |
WorktreeRemove | 移除工作树 | worktree 被移除时触发，适合清理非 git 工作副本或归档状态。 |
PreCompact | 压缩前 | 自动或手动 /compact 前触发，可阻止压缩或检查压缩条件。 |
PostCompact | 压缩后 | 压缩完成后触发，可记录摘要或同步外部状态。 |
Elicitation | 请求用户输入 | MCP 服务器在工具执行中请求用户输入时触发，可程序化响应或拒绝。 |
ElicitationResult | 用户输入结果 | 用户响应 MCP 请求后、发送回服务器前触发，可观察、改写或阻止响应。 |
SessionEnd | 会话结束 | 会话退出、清空、切换或登出时触发，用于清理任务和统计。 |
二、查看当前 Hooks
在 Claude Code 中输入：
text
/hooks这个命令可以管理和查看当前 Hook 配置。
界面中会列出 Claude Code 支持的一些触发节点。
例如：
| 节点 | 含义 |
|---|---|
Notification | Claude Code 发送通知时触发 |
SessionStart | 新会话启动、恢复、清空或压缩后重建时触发 |
Stop | 主 Claude 代理完成回复时触发 |
PreToolUse | 工具调用执行前触发 |
PostToolUse | 工具成功执行后触发 |
节点后面的数字，表示当前这个事件下面已经配置了多少个 Hook。
选中某个节点后按回车，可以查看这个 Hook 的触发条件、匹配规则和具体执行动作。
这些内容稍作了解即可。真正新增或修改 Hook，通常是改配置文件，或者直接让 Claude Code 帮你配置。
三、Hooks 保存位置
Hooks 通常保存在 Claude Code 的设置文件中。
常见位置如下：
| 配置文件 | 作用 |
|---|---|
~/.claude/settings.json | 当前用户的 Claude Code 配置 |
.claude/settings.json | 当前项目共享配置 |
.claude/settings.local.json | 当前项目本地配置 |
注意
如果 Hook 里包含飞书 Webhook、API Key 或其他凭据，更建议放在本地个人配置中，不要提交到仓库。